home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1997 May / EnigmA AMIGA RUN 18 (1997)(G.R. Edizioni)(IT)[!][issue 1997-05][EAR-CD II].iso / softwareupdate / system / amigados / advancedroutines / functions.doc < prev    next >
Text File  |  1996-10-10  |  11KB  |  333 lines
  1. 7    ADVANCED AMIGADOS ROUTINES - FUNCTIONS
  2.  
  3. 7.1  QUICK REFERENCE
  4.  
  5. Here is a complete list of all functions described in this
  6. chapter:
  7.  
  8.   Function                Description                                   
  9.   -------------------------------------------------------------
  10.   AllocDosObject()        Allocates AmigaDOS objects.
  11.   AllocDosObjectTagList() Allocates AmigaDOS objects.
  12.   AllocDosObjectTags()    Allocates AmigaDOS objects.
  13.   Examine()               Examines a file, direcotry or volume.
  14.   ExNext()                Examines objects in a directory.
  15.   FreeDosObject()         Deallocates AmigaDOS objects.
  16.   Info()                  Examines a disk.
  17.   -------------------------------------------------------------
  18.  
  19.  
  20.  
  21. ---------------------------------------------------------------
  22.  
  23. AllocDosObject(), AllocDosObjectTagList(), AllocDosObjectTags()
  24.  
  25. ROM library: "dos.library/AllocDosObject", (V37+)
  26. #include <clib/dos_protos.h>
  27.  
  28. Allocates different types of objects used by AmigaDOS. The
  29. objects will be long word aligned, and the size can vary
  30. between different dos library releases.
  31.  
  32. Synopsis: object = AllocDosObject( type, tags );
  33.  
  34.   object: (APTR) The function will return a pointer to the new
  35.           allocated object, or NULL if the object could not be
  36.           created.
  37.  
  38.   types:  (ULONG) The type of object you want to allocate:
  39.           (defined in header file "dos/dos.h")
  40.   
  41.             DOS_FIB          FileInfoBlock structure.
  42.  
  43.             DOS_FILEHANDLE   When you want to create your own
  44.                              file handler. Rarely used.
  45.  
  46.             DOS_EXALLCONTROL To create an object used by the
  47.                              ExAll() function. (See below for
  48.                              more information)
  49.  
  50.             DOS_STDPKT       When you want a "standard AmigaDOS
  51.                              Packets".
  52.  
  53.             DOS_CLI          Object needed when you write
  54.                              your own Shells.
  55.  
  56.             DOS_RDARGS       Used by the command line parsing
  57.                              routines as described in chapter 5
  58.                              "Parsing the Command Line".
  59.   
  60.   tags:   (struct TagItem *) Pointer to a list of one or more
  61.           TagItem structures which has been initialized with
  62.           your requirements, or NULL if you do not want to set
  63.           any tags.
  64.           
  65.           This tag filed is currently only used when you write
  66.           your own file handlers or Shells. The available tags
  67.           are listed in header file "dos/dos.h", but since they
  68.           are rarely used with this function I have not listed
  69.           them here. As always the last "Tag ID" must be
  70.           "TAG_DONE".
  71.           
  72.           
  73. Since this function uses the new "Tag Sytem" there exist two
  74. other options on how to call the function:
  75.  
  76. Synopsis: object = AllocDosObjectTagList( type, tags );
  77.  
  78.   This one is identical to the "AllocDosObject()" function
  79.   which we have just described. See above for information about
  80.   the arguments.
  81.  
  82. Synopsis: object = AllocDosObjectTags( type, tag1, tag2, ... );
  83.  
  84.   Similar to "AllocDosObject()", but instead of giving the
  85.   function a pointer to a list of TagItem structures you list
  86.   all tags as arguments for the function. Note that the last
  87.   "Tag ID" must as always be "TAG_DONE".
  88.  
  89.   tag1: (ULONG) The ID for tag 1.
  90.  
  91.   tag2: (ULONG) The Data for tag 1.
  92.  
  93.   tag3: (ULONG) The ID for tag 2.
  94.  
  95.   - - - and so on...
  96.  
  97.   tagX: (ULONG) The ID for tag X, must be "TAG_DONE".
  98.  
  99.  
  100. Note! All objects which are allocated with help of the
  101. AllocDosObject() function must when not needed any more be
  102. deallocated with help of the FreeDosObject() function.
  103.  
  104. Here is a simple example on how to use the AllocDosObject()
  105. function:
  106.  
  107.   /* Declare a pointer to our FileInfoBlock */
  108.   /* which we will allocate:                */
  109.   struct FileInfoBlock *my_fib;
  110.  
  111.   - - -
  112.  
  113.   /* Create a FileInfoBlock structure with help */
  114.   /* of the new AllocDosObject() function:      */
  115.   my_fib = AllocDosObject( DOS_FIB, NULL );
  116.  
  117.   /* Check if we have allocated the memory successfully: */
  118.   if( !my_fib )
  119.     printf( "Could not allocate the FileInfoBlock!\n" );
  120.  
  121.  
  122. See also: Examine(), FreeDosObject()
  123.  
  124. ---------------------------------------------------------------
  125.  
  126. Examine()
  127.  
  128. ROM library: "dos.library/Examine", (All versions)
  129. #include <clib/dos_protos.h>
  130.  
  131. Examines a file, direcotry, volume (or device) and stores some
  132. interesting information about the object in a given
  133. FileInfoBlock structure.
  134.  
  135. Synopsis: ok = Examine( lock, fib );
  136.  
  137.   ok:     (LONG) If the function managed to examine the object
  138.           it returns "DOSTRUE". On the other hand, if the
  139.           function failed to get the information it returns
  140.           "DOSFALSE".
  141.   
  142.   lock:   (BPTR) A BCPL pointer to the lock on the object you
  143.           want to examine. 
  144.   
  145.   fib:    (struct FileInfoBlock *) Pointer to a FileInfoBlock
  146.           structure in which all information will be stored.
  147.           This structure must be long word aligned.
  148.  
  149. Here is a simple example on how to use the Examine() function:
  150.  
  151.   /* AmigaDOS boolean check variable: */
  152.   LONG ok;
  153.  
  154.   - - -
  155.  
  156.   /* Get some information about an object: */
  157.   ok = Examine( my_lock, my_fib );
  158.  
  159.   /* Could we get the information? */
  160.   if( !ok )
  161.     printf( "Error! Could not examine the object!\n" );
  162.   else
  163.     printf( "OK! You may examine the FileInfoBlock structure" );
  164.  
  165.  
  166. See also: AllocDosObject(), AllocMem(), ExNext(),
  167.           FreeDosObject()
  168.  
  169. ---------------------------------------------------------------
  170.  
  171. ExNext()
  172.  
  173. ROM library: "dos.library/ExNext", (All versions)
  174. #include <clib/dos_protos.h>
  175.  
  176. Examines objects in a directory, device, or volume. Can be
  177. called several times until there are no more objects to
  178. examine.
  179.  
  180. Synopsis: ok = ExNext( lock, fib );
  181.  
  182.   ok:     (LONG) If the function managed to examine the object
  183.           it returns "DOSTRUE". On the other hand, if the
  184.           function failed to get the information it returns
  185.           "DOSFALSE".
  186.           
  187.           When this function fails you should call the IoErr()
  188.           function to get more information about the error. If
  189.           IoErr() returns "ERROR_NO_MORE_ENTRIES" there were
  190.           simply no more objects in the directory (device/
  191.           volume), but if IoErr() returns anything else there
  192.           was some sort of "real" error.
  193.  
  194.   lock:   (BPTR) A BCPL pointer to the lock you used when you
  195.           first called Examine().
  196.   
  197.   fib:    (struct FileInfoBlock *) Pointer to a FileInfoBlock
  198.           structure in which all information will be stored.
  199.           This structure must be long word aligned, and you
  200.           may not alter any of the fields while you are
  201.           collecting objects. You may only read the values,
  202.           not modify them!
  203.  
  204. After you have successfully examined a directory, device or
  205. volume with help of the Examine() function you can use this
  206. function to get information about the objects in that
  207. directory, device or volume. To examine all objects simply
  208. call this function over and over again until it fails because
  209. there are no more objects left to examine, or there was some
  210. sort of error.
  211.  
  212. Here is a simple example on how to use the ExNext() function:
  213. (You must of course first have called the Examine() function
  214. and checked that it really is a directory (device or volume)
  215. before you may call ExNext().)
  216.  
  217.   - - -
  218.   
  219.   /* As long as we find objects we stay in the loop and */
  220.   /* prints the name of the objects we find:            */
  221.   while( ExNext( my_lock, my_fib ) )
  222.     printf( "%s\n", my_fib->fib_FileName );
  223.  
  224.   /* The ExNext() function has now failed. Check if it simply */
  225.   /* was no more objects left to examine or if there really   */
  226.   /* was an error:                                            */
  227.   if( IoErr() == ERROR_NO_MORE_ENTRIES )
  228.     printf( "OK! No more files!\n" );
  229.   else
  230.     printf("Error while reading!\n");
  231.  
  232.  
  233. See also: Examine()
  234.  
  235. ---------------------------------------------------------------
  236.  
  237. FreeDosObject()
  238.  
  239. ROM library: "dos.library/FreeDosObject", (V37+)
  240. #include <clib/dos_protos.h>
  241.  
  242. Deallocates objects that was created by a previous call to the
  243. AllocDosObject() function.
  244.  
  245. Synopsis: FreeDosObject( type, tags );
  246.  
  247.   types:  (ULONG) The type of object that should be
  248.           deallocated: (You must of course use the same type
  249.           as when you allocated the object. See function
  250.           AllocDosObject() for more information about the
  251.           available types.)  
  252.  
  253.             DOS_FIB         
  254.             DOS_FILEHANDLE  
  255.             DOS_EXALLCONTROL
  256.             DOS_STDPKT      
  257.             DOS_CLI         
  258.             DOS_RDARGS      
  259.   
  260.   object: (APTR) Pointer to the object that should be
  261.           deallocated.
  262.           
  263. Note! All objects which are allocated with help of the
  264. AllocDosObject() function must when not needed any more be
  265. deallocated with help of this FreeDosObject() function.
  266.  
  267. Note! Only objects which were created by AllocDosObject() may
  268. be deallocated with this function.
  269.  
  270. Here is a simple example on how to use the FreeDosObject()
  271. function:
  272.  
  273.   - - -
  274.  
  275.   /* Deallocate the FileInfoBlock structure wich we have */
  276.   /* created with help of the AllocDosObject() function: */
  277.   FreeDosObject( DOS_FIB, my_fib );
  278.  
  279.  
  280. See also: AllocDosObject(), Examine()
  281.  
  282. ---------------------------------------------------------------
  283.  
  284. Info()
  285.  
  286. ROM library: "dos.library/Info", (All versions)
  287. #include <clib/dos_protos.h>
  288.  
  289. Examines a disk and stores some interesting information about
  290. it in an InfoData structure.
  291.  
  292. Synopsis: ok = Info( lock, info );
  293.  
  294.   ok:     (LONG) If the function managed to examine the disk
  295.           it returns "DOSTRUE". On the other hand, if the
  296.           function failed to get the information it returns
  297.           "DOSFALSE".
  298.           
  299.   lock:   (BPTR) A BCPL pointer to a lock on the disk you want
  300.           to examine.
  301.   
  302.   info:   (struct InfoData *) Pointer to an InfoData structure
  303.           which will be used to store all information in.
  304.           Please note that since you have to supply this
  305.           function with your own structure is must be long
  306.           word aligned! 
  307.  
  308. Here is a simple example on how to use the Info() function:
  309.  
  310.   /* If the function was successful or not: */
  311.   LONG ok;
  312.  
  313.   - - -
  314.  
  315.   /* Examine the disk: */
  316.   ok = Info( my_lock, my_info_data );
  317.   if( ok )
  318.   {  
  319.     /* Print some info about the disk: */
  320.     if( my_info_data->id_DiskState == ID_WRITE_PROTECTED )
  321.       printf( "The disk is Write Protected!\n" );
  322.  
  323.     if( my_info_data->id_DiskState == ID_VALIDATED )
  324.       printf( "The disk is Not (Write) Protected!\n" );
  325.   }
  326.   else
  327.     printf( "Could not examine the disk!\n" );
  328.  
  329.  
  330. See also: AllocMem(), Lock()
  331.  
  332. ---------------------------------------------------------------
  333.